Docs 是知識的書面紀錄。通常他能讓我們用最少的文字 去理解整件事情的全貌。
對於一個 repo 也是一樣，好的 Docs 能讓我們在不用去理解程式碼的情況下，了解程式碼所帶來的功能與意義。
我們可以把 docs 想像成 錨點：不論是人或 agent，當今天是新進人員，或者討論過於發散時，都能透過它快速掌握專案目前所扮演的地位與角色。
人員會更替、記憶會淡化；coding agent 的情況更為極端，每個新的 session 都從零開始，它所掌握的只有當下讀進 context 的內容。作為錨點的 docs，能有效地傳承知識，幫助人與 agent 快速理解專案。
但 docs 本身也是 context 的一部分。正因為它是錨點，會被反覆讀取，並持續影響每一位讀者的判斷。
因此，Day3 整理的 context 問題同樣會出現在 docs 上：docs 的品質，會直接成為 context 的品質。
這也是為什麼 docs 的核心不在於「寫得越多越好」，而在於：只保留必要、品質良好，且目前仍然有效的 docs。
Survey 一圈，會看到各式各樣的文件名稱：README、spec、runbook、design doc、RFC、ADR、plan……。
文件名稱雖多，但分類的重點不在名稱，而在文件的生命週期，以及由誰負責維持其正確性。 從這個角度來看，大致可以歸納為三類：
這三類文件對人與 agent 同樣重要，但對 agent 來說，錯誤文件的代價更高。agent 的 context 長度有限，讀進錯誤資訊不僅會降低處理問題的品質；即使 agent 能自行察覺並修正，也得耗費大量的時間與 token。
Current truth 描述的是系統目前的狀態，因此要求也最嚴格：只要與現況不符，它就是錯誤的。
為了維持正確性，這類文件應與 code 一同修改、一同 review：系統行為變更時，對應的文件更新應包含在同一個 commit 中，而非事後補寫。
README 回答的是：這個專案是什麼？該如何開始？
內容應保持高層次且精簡：專案目的、quick start、基本環境設定，以及重要文件的連結。
README 通常也會涵蓋另外兩種 current truth：
專案規模尚小時，將這些內容全部放在 README 中並無問題。
但隨著內容增加，每位讀者都會被迫讀進所有細節：agent 可能只需要了解專案的用途，卻連同所有操作步驟與規格一併讀進 context，造成 context 污染。
因此，好的 README 更接近一個 orientation layer（導覽層）：本身只負責回答「這是什麼、如何開始」，並將 Spec、Runbook、Design doc、ADR 拆分為獨立文件並加以連結，讓讀者依任務需求再深入閱讀。
Spec 描述系統應滿足的條件：
Code 描述系統「實際做了什麼」，spec 描述系統「應該做什麼」；兩者不一致時，代表其中一方需要修正。
Spec 也會出現在 Working state 中，那是它產生的階段；此處的 spec，則是工作完成後累積下來的系統現況。
Runbook 描述系統的操作方式：
它的標準很明確：依照步驟執行，就能完成任務。 只要其中一個步驟與現況不符，整份 runbook 便會失去可信度。
README、Spec 與 Runbook 分別回答「這是什麼」、「應該做什麼」與「如何操作」。三者各司其職：README 作為入口，Spec 與 Runbook 則在需要時才深入閱讀。如此一來，無論是人或 agent，都能依任務只讀進必要的內容，而讀進的每一份，都是系統的現況。
What 通常能從 code 看出來，但 why 很容易隨時間消失。
Code 只記錄最後的選擇，不會記錄選擇的理由，也不會保留未被採用的方案。Design knowledge 類的文件，正是為了保存設計背後的理由而存在。
Design doc 記錄的是一整場設計討論，在 Google，多數團隊啟動重大專案前都會要求先完成一份。內容通常包含：
正因為記錄的是討論過程，design doc 往往相當龐雜：有些內容在決策後便不再適用，有些只是討論途中產生、尚未成熟的想法。這些內容對當下的討論有其價值，但對之後接手的人或 agent 而言，大多只是雜訊。
因此在決策完成後，會從中提煉出一份精簡的 ADR。
ADR 從 design doc 中抽出值得長期保存的決策：
ADR 建議與 application code 放在一起，並納入同一個版本控制系統。
決策改變時，由新 ADR 在背景中說明被取代的決策與原因。舊 ADR 若被完全取代，便從 repo 移除，原文留在 git 歷史中；若僅部分取代，則只保留仍然有效的部分。Nygard 的原始做法是保留舊 ADR 並標記為 superseded，但對 agent 而言，與目前 code 無關的決策只是雜訊，甚至可能讓它依據早已被推翻的理由修改 code。
Design doc 是過程，ADR 是結論。 因此 repo 中可以只保留 ADR，完整的 design doc 另行存放，需要追溯時再查閱。
Working state 是本次工作的文件，只在工作期間有效。
Plan 與 spec 都應在工作開始前定義完成，再交由 agent 執行。
它是本次工作的最終驗收依據，也是撰寫 test 的基礎。
如 Day3 所述，在工作開始時就提供完整的 plan，效果會優於在對話中逐步補充。
驗收完成後：
Working state 若未被清理，就會成為最典型的過期文件。
水能載舟，亦能覆舟。
乾淨的 docs 能有效幫助 agent，品質不佳的 docs 則會讓 agent 的表現更差。
多數人都了解 docs 的重要性，也經常讓 AI 協助撰寫。但若各類文件的職責沒有劃分清楚，就很容易產生上千行、主題混雜的文件。問題不在於不想寫好，而在於沒有釐清每一種文件的定義：不知道一段內容該放在哪裡、該保留多久、何時該刪除，只能不斷往裡面追加。
釐清三種類型之後，每一份文件都能對應到明確的規則：
| 文件 | 類型 | 存放位置 | 內容 | 更新／移除時機 |
|---|---|---|---|---|
| README | Current truth | repo 根目錄，以及各模組目錄 | 專案目的、quick start、重要文件連結 | 相關內容變更時，與 code 同一個 commit 更新 |
| Spec | Current truth | repo 內 | 系統應滿足的行為與限制 | 系統行為變更時，與 code 同一個 commit 更新 |
| Runbook | Current truth | repo 內 | 啟動、部署與問題排查步驟 | 操作流程變更時，與 code 同一個 commit 更新 |
| Design doc | Design knowledge | repo 外另行存放 | 完整的設計討論過程 | 決策完成後封存，供日後追溯 |
| ADR | Design knowledge | repo 內，靠近 code | 決策背景、考慮過的方案與理由 | 新決策時新增；完全取代時移除，部分取代時更新 |
| Spec（本次工作） | Working state | 工作期間暫存 | 目標、範圍與驗收標準 | 完成後合併進系統 spec，並轉為 test |
| Plan | Working state | 工作期間暫存 | 實作步驟與目前進度 | 工作期間持續更新；完成後移除 |
有了規則，agent 就不只是 docs 的讀者，也能成為維護者：
Docs 的價值不在數量，而在於每一份文件都清楚自己的定位與生命週期。
iThome鐵人賽
看影片追技術